The Arsenal Files 6/The Arsenal Files 6 (Arsenal Computer).ISO/os2bbs/va1b1-o2.zip/SCRIPT.DOC

Text File | 1996-01-28 | 14KB | 455 lines

         SCRIPT.DOC - Using This Document
         ══════════

                Throughout this document, script code fragments (examples)
         are preceeded by the characters ">>", with especially important
         lines denoted by "* >>".

         SCRIPT FILES
         ════════════

                Scripts are one of the many ways in which you can modify
         or customize the look, feel, and functionality of your BBS.
         Script files are simple ASCII text files.  They must have a
         .V filename extension, and they reside in the Script Directory,
         usually C:\VADV\V, although this will differ if you installed
         to a different drive and/or directory.  Script files do NOT require
         compilation.

                It is recommended that you use a plain text editor to create
         and modify scripts, such as MS-DOS EDIT or similar.  If you wish
         to use something fancier, such as Word for Windows, make sure
         you save your script file in Text Format.  (Other word processors
         may refer to this as ASCII or Plain Text format.)

         BASIC SYNTAX
         ════════════

                A script file is basically just lines of text.  A line may
         be blank, or contain a comment, a label, or a command with
         accompanying keywords and/or arguments.  Here is an example
         showing a blank line:

     >>  cls
   * >>
     >>  ? "Hello World!"

         The "'" character at the start of a line denotes a comment.
         Here is an example showing a comment:

     >>  cls
   * >>  'Now This is a comment
     >>  ? "Hello World!"

         The ":" character denotes a label.  Note the placement of
         the ":" at the END of the label.  Here is an example showing
         a label:

     >>  cls
     >>  gosub printmsg
     >>  exit
     >>
   * >>  printmsg:
     >>  ? "Hello World!"
     >>  return

         Notice that the ":" is left off when the label is actually
         used in a GOTO or GOSUB command.

         SIMPLE VARIABLES
         ════════════════

                260 simple variables are available for use by your script.
         Variables names are limited up to two characters; the first character
         must be a character from "A" to "Z", and the second character must
         be a digit from "0" to "9".  (That means you have variables
         A0 to A9, B0 to B9, and so on up to Z0 to Z9.)

         Note that if you use a single-character variable name, as in:

     >>  let a = 10

         Thats the same as writing:

     >>  let a0 = 10

         GLOBAL ARRAY VARIABLE
         ═════════════════════

                You have one global array to use.  It has slots 0 to 255.
         You indicate that you want to access the global array by using
         the "$" character.  You may access a slot by using a number or
         a variable.  This is an example using a number:

     >>  print $12

         It prints out the contents of whatever was in slot 12.  This
         is an example using a simple variable:

     >>  let y1 = 10
     >>  print $y1

         This is an example showing how to clear out the global array
         using a DO-LOOP structure:

     >>  do i,1,100
     >>   let $i = ""
     >>  loop

         SPECIAL VALUES
         ══════════════

                The "!" character indicates access to the special values,
         and works similarly to the global array variable.  Here are two
         examples that both do the exact same thing:

     >>  print !12

     >>  let z = 12
     >>  print !z

         !12 happens to be the current channel number.

         The special values are divided into groups based on their
         function.  Those groups are a) Functionals, b) System, c) Color,
         d) User Record, and e) Database.

         a) Functionals
         --------------

                Functionals take values from the simple vairables x, y, and
         z, as shown below.  You must use the LET command to set the x
         (and sometimes y and z) variable(s) before trying to use the
         function.  While the example show here primary use the PRINT
         command to illustrate usage, it is important note that you
         can freely use functions in string and numeric expressions.

         0  chr(x)  -  Character Function

     >>  let x=65
     >>  print !0

         The above example would print the character "A", since "A"
         is the character represented by the ASCII code 65.  Valid
         values for x the standard ASCII codes, 0 to 255.

         1  asc(x)  -  ASCII Code Function

     >>  let x="A"
     >>  print !1

         The above example would print the number 65, since 65
         is the ASCII code for the character "A".

         2  sqr(x)  -  Square Root Function

     >>  let x=4
     >>  print !2

         The above example would print the result 2, since 2 is the square
         root of 4.

         3  int(x)  -  Integer Function

     >>  let x=5.5
     >>  print !3

         The above example would print the result 5, chopping off
         the fractional part of the number.

         4  abs(x)  -  Absolute Value Function

     >>  let x=-4
     >>  print !4

         The above example would print the result 4.

         5  ucase(x)  -  Upper Case Function

     >>  let x="Hello World!"
     >>  print !5

         The above example would print the string "HELLO WORLD!".

         6  rnd(x)

     >>  let x=1
     >>  print !6

         The above example would print a random floating-point number
         from 0 to 1.  To generate a random number between 1 and some
         given limit, for example 100, use some arithmetic:

     >>  let x=1
     >>  let x=!6*100        <------ get random number, multiply by
     >>  let x=!3+1          <--     100, and store result back in x.
                               |
                               ----- use int(x) function to truncate any
                                     remaining fractional part and add 1.

         7  len(x)  -  String Length Function

     >>  let x="Hello World!"
     >>  print !7

         The above example would print the result 12.

         8  instr(x,y)  -  InString Function

     >>  let x="ABCD"
     >>  let y="C"
     >>  print !8

         The above example would print the result 3, since the substring
         "C" is in the third position of the mainstring "ABCD".  If the
         substring cannot be found the result is zero.

         9  left(x,y)  -  Left String Function

     >>  let x="ROLAND DE GRAAF"
     >>  let y=6
     >>  print !9

         The preceeding example would print the string "ROLAND".

         10 mid(x,y,z)  -  Mid String Function

     >>  let x="ABC"
     >>  let y=2              <---- set position
     >>  let z=1              <---- set number of characters to retrieve
     >>  print !10

         The above example would print the string "B".

         11 right(x,y)  -  Right String Function

     >>  let x="ROLAND DE GRAAF"
     >>  let y=8
     >>  print !11

         The preceeding example would print the string "DE GRAAF".

         b) System
         ---------

         12  Channel Number
         13  Carriage Return
         14  Date
         15  Date/Human Format
         16  Time
         17  Highest NetworkID #
         18  NetName(x)
         19  BBS Name
         20  SysOp Name
         21  YN<cr>
         22  Global Result Code
         23  Current Video Mode
         24  Reserved
         25  Reserved
         26  Reserved
         27  Reserved
         28  Reserved
         29  Reserved

         c) Colors
         ---------

         30  Normal Color
         31  Red
         32  Green
         33  Yellow
         34  Blue
         35  Magenta
         36  Cyan
         37  White
         38  Bold
         39  Base Color
         40  Prompt Color
         41  Input Color
         42  Reserved
         43  Reserved
         44  Reserved
         45  Reserved
         46  Reserved
         47  Reserved
         48  Reserved
         49  Reserved

         The following two examples both accomplish the same effect:

     >>  print !31, "Red", !32, "Green"

     >>  print !31 % "Red" % !32 % "Green"

         Note that "%" is the string concatenation operator.

         d) User Record
         --------------

                The user record variables let you have access to the user's
         account data.  The ones marked with an asterisk "*" are also
         writable.

         50  User Number
         51* User Handle
         52* User Name
         53* User Video Mode
         54* User Security Level
         55* User Time Limit
         56* User Access Flags
         57* User Flags
         58* User Credits
         59* User Expiration Date
         60* User Page Size
         61* User Extra #1
         62* User Extra #2
         63* User Extra #3
         64* User Extra #4
         65* User Extra #5
         66* User Extra #6
         67* User Extra #7
         68* User Extra #8
         69  User Total Mins Online
         70  User Total Number of Calls
         71  User Time On (Current Login)
         72  User Time Left (Current Login)
         73* User Video Mode
         74* User # of Files Downloaded
         75* User # of Kilobytes Downloaded
         76* User # of Files Uploaded
         77* User # of Kilobytes Uploaded
         78* User # of Emails
         79* User # of Posts
         80* User Address
         81* User City
         82* User State
         83* User Zip Code
         84* User Phone #1
         85* User Phone #2
         86  User Age
         87  Reserved
         88  Reserved
         89  Reserved

         This is an example showing how to set the security level:

     >>  let !54 = 100

         This is an example showing how to increase a user's credits by 500:

     >>  let !58 = !58 + 500

         e) Database Access
         ------------------

                The first 3 values, 90 through 92 are set by your use
         of the script DBGROUP command, which selects a topic group:

         90  Current Topic Group Letter
         91  Current Topic Group Description
         92  Number of Databases in Group

         The values 93 through 99 are set by your use of the script
         DB command, which selects a database within the current
         topic group:

         93  Current Database Number
         94  Current Database Description
         95  Number of Entries in Database
         96  Next-New-Message Read Pointer
         97  Database Filename (no extension)
         98  Database Attached-File Storage Path
         99  Database Maximum

         The values 100 through 117 are set by your use of the script
         LOAD command, which loads data one entry from the currently
         selected database:

         100 Subject
         101 From field, Handle or Name
         102 From field, User number (0=Not Applicable)
         103 From field, Network Address
         104 From field, NetworkID
         105 To field, Handle or Name
         106 To field, User number (0=Not Applicable)
         107 To field, Network Address
         108 To field, NetworkID
         109 Date/Time Stamp (String)
         110 Count
         111 Attached Filename (If Any)
         112 Attached File Size (0=None)
         113 Attached File/Full Path Format (If Any)
         114 Offset into BIN file of text component
         115 Length of BIN file text component
         116 Date/Time Stamp (Numeric)
         117 Flag field

         STRING LITERALS
         ═══════════════

                A string literal is just a sequence of characters, enclosed
         in double quotes, such as "string literal".  Here are some examples
         using string literals:

     >>  print "Hello World!"

     >>  let x="ABCD"

     >>  exit "main"

     >>  if a="Y" goto yes

         STRING EXPRESSIONS
         ══════════════════

         NUMERIC EXPRESSIONS
         ═══════════════════

                The following mathematical, bitwise, and relational operators
         are available for use in numeric expressions:

         ^ Exponentiation
         + Addition
         - Subtraction
         * Multiplication
         / Floating-Point Division
         \ Integer Division
         # Modulo Arithemtic

         | Bitwise OR
         & Bitwise AND

         >  Greater Than
         >= Greater Than Or Equal
         <  Less Than
         <= Less Than or Equal
         =  Equal
         <> Not Equal

         COMMAND REFERENCE
         ═════════════════

         TIPS
         ════

                You have up to 260 simple variables for use.  If you should
         run out, feel free to use slots in the global array as simple
         variables (ie. $0, $1, $2, and so on).  The only limitation
         is that global array slots cannot be used as the index variable
         in a DO-LOOP structure.

                Simple Variables and the Global Array Variable are NOT
         automatically cleared when a script is started, or when the LINK
         command is used to branch to another script.  Therefore, you must
         explicitly use the LET command to clear or zero any variables
         which you want cleared.

     >>  let a = ""

     >>  let b = 0

         This also means that you may pass information or data values
         from one script to another.